Search API
Search service API Documentation
Paths
/cl/search/api/v1/healthz/
- Method: GET
- Summary: Health
- Description: Return Health Status. :return:
- Operation ID: health_cl_search_api_v1_healthz__get
- Responses:
- 200:
- Description: Successful Response
- Content-Type: application/json
- 200:
Semantic Search API
/cl/search/api/v1/semantic
-
Method:
POST
-
Summary: Semantic Search On Tenant Data
-
Description: Perform a semantic search on tenant data present in the object repository and return a list of matching documents.
-
Operation ID: Semantic_search_on_tenant_data_present_cl_search_api_v1_semantic_post
Request Payload:
Type | Parameter | Description | Data Type | is_optional |
---|---|---|---|---|
Query Parameter | query_string | Query string to search for objects semantically | string | mandatory |
Query Parameter | start | Specifies the page number to retrieve (1-based index) | int | mandatory |
Query Parameter | size | Specifies the number of items per page | int | mandatory |
Query Parameter | min_relevant_score | Minimum relevant score | int | mandatory |
Parameter | tags | List of tags associated with the document | array of strings | mandatory |
Parameter | folders | List of folders where the document is organized | array of strings | mandatory |
Parameter | repos | List of repositories where the document is stored | array of strings | mandatory |
Parameter | kvp | Key-value pairs for additional metadata | object | mandatory |
Parameter | taxonomy | Taxonomy information related to the document | array of objects | mandatory |
sample code
import requests
URL = "https://api.kadal.ai/cl/search/api/v1/semantic"
# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_string":"string",
"start":"int",
"size":"int",
"min_relevant_score":"int",
"tags": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": {},
"taxonomy": {}
}
response = requests.post(URL, headers=headers,params=params)
print(response)
Example response -
{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}
Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Documents found | application/json |
400 | Bad Request | application/json |
401 | Unauthorized | application/json |
403 | Forbidden | application/json |
404 | Object not found | application/json |
405 | Method not allowed | application/json |
422 | Unprocessable Entity | application/json |
500 | Internal server error | application/json |
- 200 (Documents found): This response indicates that the semantic search operation was successful, and it returns a list of matching documents.
- 400 (Bad Request): This response indicates that the request was malformed or invalid.
- 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
- 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
- 404 (Object not found): This response indicates that the requested object or resource was not found.
- 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
- 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
- 500 (Internal server error): This response indicates an unexpected server error occurred.
Note: Use this API to perform a semantic search on tenant data present in the object repository. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.
Full-Text Search API
/cl/search/api/v1/fulltext
-
Method:
POST
-
Summary: Full-Text Search On Tenant Data
-
Description: Perform a full-text search on tenant data present in the object repository and return a list of matching documents.
-
Operation ID: Full_text_search_on_tenant_data_present_cl_search_api_v1_fulltext_post
Request Payload:
Type | Parameter | Description | Data Type | is_optional |
---|---|---|---|---|
Query Parameter | query_string | Query string to search for objects semantically | string | mandatory |
Query Parameter | start | Specifies the page number to retrieve (1-based index) | string | mandatory |
Query Parameter | size | Specifies the number of items per page | int | mandatory |
Query Parameter | min_relevant_score | Minimum relevant score | int | mandatory |
Parameter | tags | List of tags associated with the document | list | mandatory |
Parameter | folders | List of folders where the document is organized | list | mandatory |
Parameter | repos | List of repositories where the document is stored | list | mandatory |
Parameter | kvp | Key-value pairs for additional metadata | list | mandatory |
Parameter | taxonomy | Taxonomy information related to the document | list | mandatory |
sample code
import requests
URL = "https://api.kadal.ai/cl/search/api/v1/fulltext"
# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_string":"string",
"start":"int",
"size":"int",
"min_relevant_score":"int",
"tags": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": "list",
"taxonomy": "list",
}
response = requests.post(URL, headers=headers,params=params)
print(response)
Example response -
{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}
Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Documents found | application/json |
400 | Bad Request | application/json |
401 | Unauthorized | application/json |
403 | Forbidden | application/json |
404 | Object not found | application/json |
405 | Method not allowed | application/json |
422 | Unprocessable Entity | application/json |
500 | Internal server error | application/json |
- 200 (Documents found): This response indicates that the full-text search operation was successful, and it returns a list of matching documents.
- 400 (Bad Request): This response indicates that the request was malformed or invalid.
- 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
- 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
- 404 (Object not found): This response indicates that the requested object or resource was not found.
- 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
- 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
- 500 (Internal server error): This response indicates an unexpected server error occurred.
Note: Use this API to perform a full-text search on tenant data present in the object repository. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.
Basic Search API
/cl/search/api/v1/basic_search
-
Method:
POST
-
Summary: Basic Search On Tenant Data
-
Description: Perform a basic search on tenant data present in the object repository and return a list of matching documents based on a specified query.
-
Operation ID: Basic_search_on_tenant_data_present_cl_search_api_v1_basic_search_post
Request Payload:
Query Parameter | Parameter | Description | Data Type | is_optional |
---|---|---|---|---|
query_string | provide string query | object (dictionary) | Yes | |
kvp | Key-value pairs for additional metadata | dictionary | Yes | |
tags | List of tags associated with the request | strings | Yes | |
repos | List of repositories linked to the request | strings | Yes | |
folders | List of folders associated with the request | strings | Yes | |
created_between | Filter results by creation date range | list | Yes | |
modified_between | Filter results by modification date range | list | Yes | |
deleted_between | Filter results by deletion date range | list | Yes | |
start | Index of the first item to retrieve in the result set | integer | No | |
size | Number of items to retrieve per page | integer | No |
sample code
import requests
URL = "https://api.kadal.ai/cl/search/api/v1/basic_search"
# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_dictionary": {
"kvp": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"tags": [
"string"
],
"repos": [
"string"
],
"folders": [
"string"
],
"start": "int",
"size": "int",
"source": "string",
"created_between": "list",
"modified_between": "list",
"deleted_between":"list",
}
}
response = requests.post(URL, headers=headers,params=params)
print(response)
Example response -
{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}
Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Documents found | application/json |
400 | Bad Request | application/json |
401 | Unauthorized | application/json |
403 | Forbidden | application/json |
404 | Object not found | application/json |
405 | Method not allowed | application/json |
422 | Unprocessable Entity | application/json |
500 | Internal server error | application/json |
- 200 (Documents found): This response indicates that the basic search operation was successful, and it returns a list of matching documents based on the query.
- 400 (Bad Request): This response indicates that the request was malformed or invalid.
- 401 (Unauthorized): This response indicates that the request lacks valid authentication credentials for the operation.
- 403 (Forbidden): This response indicates that the request is forbidden due to insufficient permissions.
- 404 (Object not found): This response indicates that the requested object or resource was not found.
- 405 (Method not allowed): This response indicates that the HTTP method used is not allowed for this endpoint.
- 422 (Unprocessable Entity): This response indicates that the request was well-formed but unable to be followed due to semantic errors.
- 500 (Internal server error): This response indicates an unexpected server error occurred.
Note: Use this API to perform a basic search on tenant data present in the object repository using a specified query. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.
Search APIs
/cl/search/api/v1/search
-
Method:
POST
-
Summary: Search With Reranking
-
Description: Re-rank search results obtained through semantic and full-text search.
-
Operation ID: search_with_reranking_cl_search_api_v1_search_post
Request Payload:
Type | Parameter | Description | Data Type | is_optional |
---|---|---|---|---|
Query Parameter | query_string | Query string to search | string | mandatory |
Query Parameter | top_k | Default value for top_k (Default: 5) | int | mandatory |
Query Parameter | re_ranked | Re-rank the search results | boolean | mandatory |
Parameter | tags | List of tags associated with the document | list | mandatory |
Parameter | folders | List of folders where the document is organized | list | mandatory |
Parameter | repos | List of repositories where the document is stored | list | mandatory |
Parameter | kvp | Key-value pairs for additional metadata | list | mandatory |
Parameter | taxonomy | Taxonomy information related to the document | list | mandatory |
sample code
import requests
URL = "https://api.kadal.ai/cl/search/api/v1/search"
# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_string":"string",
"top_k":"int",
"re_ranked":"bool",
"tags": [
"string"
],
"object_ids": [
"string"
],
"folders": [
"string"
],
"repos": [
"string"
],
"kvp": "list",
"taxonomy": "list",
}
response = requests.post(URL, headers=headers,params=params)
print(response)
Example response -
{
"status": "string",
"message": "string",
"data": "string"
}
Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Successful Response | application/json |
422 | Validation Error | application/json |
- 200 (Successful Response): This response indicates that the search with reranking operation was successful.
- 422 (Validation Error): This response indicates that there was a validation error with the request.
/cl/search/api/v1/search_lite
-
Method:
GET
-
Summary: Search With Reranking
-
Description: Search the database for similar documents using k-nn search provided by OpenSearch.
-
Operation ID: search_with_reranking_cl_search_api_v1_search_lite_get
Request Payload:
Type | Parameter | Description | Data Type | is_optional |
---|---|---|---|---|
Parameter | query_string | Query string to search | string | mandatory |
Parameter | top_k | Default value for top_k (Default: 5) | int | mandatory |
Parameter | re_ranked | Re-rank the search results for similar documents | boolean | mandatory |
sample code
import requests
URL = "https://api.kadal.ai/cl/search/api/v1/search_lite"
# sample python code
headers = { "Authorization ": "Bearer 1234567890" }
params={
"query_string":"string",
"top_k":"int",
"re_ranked":"bool"
}
response = requests.get(URL, headers=headers,params=params)
print(response)
Example response -
{
"status": "string",
"message": "string",
"data": "string"
}
Responses:
Status Code | Description | Content-Type |
---|---|---|
200 | Successful Response | application/json |
422 | Validation Error | application/json |
- 200 (Successful Response): This response indicates that the search with reranking operation was successful.
- 422 (Validation Error): This response indicates that there was a validation error with the request.
Note:
- Use
/cl/search/api/v1/search
to perform a search with reranking on search results obtained through semantic and full-text search. - Use
/cl/search/api/v1/search_lite
to perform a search for similar documents using k-nn search provided by OpenSearch. Ensure that the request parameters are correctly formatted and that authentication credentials are provided as required.
Components
Schemas
BasicSearchRequest
- Type: object
- Description:
- Properties:
- kvp:
- Type: object
- tags:
- Type: array
- repos:
- Type: array
- folders:
- Type: array
- created_between:
- Type: array
- modified_between:
- Type: array
- deleted_between:
- Type: array
- start:
- Type: integer
- size:
- Type: integer
- kvp:
Body_Full_text_search_on_tenant_data_present_cl_search_api_v1_fulltext_post
- Type: object
- Description:
- Properties:
- tags:
- Type: array
- folders:
- Type: array
- repos:
- Type: array
- kvp:
- Type: object
- taxonomy:
- Type: object
- tags:
Body_Semantic_search_on_tenant_data_present_cl_search_api_v1_semantic_post
- Type: object
- Description:
- Properties:
- tags:
- Type: array
- folders:
- Type: array
- repos:
- Type: array
- kvp:
- Type: object
- taxonomy:
- Type: object
- tags:
Body_search_with_reranking_cl_search_api_v1_search_post
- Type: object
- Description:
- Properties:
- tags:
- Type: array
- object_ids:
- Type: array
- folders:
- Type: array
- repos:
- Type: array
- kvp:
- Type: object
- taxonomy:
- Type: object
- tags:
HTTPValidationError
- Type: object
- Description:
- Properties:
- detail:
- Type: array
- detail:
Msg
- Type: object
- Description:
- Properties:
- msg:
- Type: string
- msg:
QueryResponse
- Type: object
- Description:
- Properties:
- status:
- Type: string
- message:
- Type: string
- result_count:
- Type: integer
- result:
- aggregations:
- status:
ValidationError
- Type: object
- Description:
- Properties:
- loc:
- Type: array
- msg:
- Type: string
- type:
- Type: string
- loc:
Search Service API Documentation
Version: 2.0.0
Overview
This API provides comprehensive search capabilities for content stored in LOR-NG. It supports various search types including basic search, semantic search, fulltext search, and re-ranked search operations.
Authentication
The API uses OAuth 2.0 with Bearer token authentication. Include the following header in all requests:
Authorization: Bearer <your_token>
API Versions
The API is available in multiple versions with different capabilities:
API v1
- Basic health check endpoint
- Legacy search endpoints
API v2
- Basic Search
- Fulltext Search
- Semantic Search
- Re-ranked Search
- Chunk Search
API v3
- Classify and Re-ranked Search
- Enhanced Basic Search with folder support
Endpoints
Health Check
GET /cl/search/api/v1/healthz/
Returns the health status of the service.
Response:
- 200: Successful Response (application/json)
Search Endpoints
1. Semantic Search
POST /cl/search/api/v2/semantic
Description: Perform a semantic search on tenant data present in the object repository.
Request Payload:
Type | Parameter | Description | Required |
---|---|---|---|
Query Parameter | query_string | Query string to search for objects | Yes |
Query Parameter | sorting_by | Sorting by (Available values: None, title, updated_at) | No |
Query Parameter | order | Sort result in ascending or descending order (Available values: None, asc, desc) | No |
Query Parameter | page_no | Default value: 1 | No |
Query Parameter | page_size | Default value: 20 | No |
Query Parameter | min_relevant_score | Default value: 0.5 | No |
Parameter | object_ids | List of object IDs | Yes |
Parameter | folders | List of folders | Yes |
Parameter | object_type | List of object types | Yes |
Parameter | file_extension | List of file extensions | Yes |
Parameter | title | Title of the object | Yes |
Parameter | size | Size of the object | Yes |
Parameter | file_name | List of file names | Yes |
Parameter | repos | List of repositories | Yes |
Parameter | ext_user_id_ref | External user ID reference | Yes |
Parameter | system_metadata | Metadata for system (created_by, updated_by, etc.) | Yes |
Parameter | custom_metadata | Custom metadata (tags, kvp, taxonomy) | Yes |
Parameter | media_metadata | Metadata related to media | Yes |
Parameter | source_system_metadata | Source system metadata (source_system_id, source_url, etc.) | Yes |
Request Payload Structure:
{
"query_string": "<string>",
"start": "<integer>",
"size": "<integer>",
"min_relevant_score": "<integer>",
"tags": ["<string>"],
"folders": ["<string>"],
"repos": ["<string>"],
"kvp": {
"key1": "value1",
"key2": "value2"
},
"taxonomy": {
"taxonomy_key1": "taxonomy_value1",
"taxonomy_key2": "taxonomy_value2"
}
}
Sample Code:
import requests
URL = "https://api.kadal.ai/cl/search/api/v2/semantic"
headers = {"Authorization": "Bearer 1234567890"}
params = {
"query_string": "string",
"start": 1,
"size": 10,
"min_relevant_score": 0,
"tags": ["string"],
"folders": ["string"],
"repos": ["string"],
"kvp": {},
"taxonomy": {}
}
response = requests.post(URL, headers=headers, json=params)
2. Full-Text Search
POST /cl/search/api/v2/fulltext
Description: Perform a full-text search with relevance scoring.
Request Payload:
Type | Parameter | Data Type | Description | Required |
---|---|---|---|---|
Query Parameter | query_string | string | Query string to search for objects | Yes |
Query Parameter | sorting_by | string | Sorting criteria (Available values: None, title, updated_at; Default: None) | No |
Query Parameter | order | string | Sort order (Available values: None, asc, desc; Default: asc) | No |
Query Parameter | page_no | integer | Page number (Default: 1) | No |
Query Parameter | page_size | integer | Items per page (Default: 20) | No |
Query Parameter | min_relevant_score | number | Minimum relevance score (Default: 0.5) | No |
Parameter | object_ids | array | List of object IDs | No |
Parameter | folders | array | List of folders | No |
Parameter | object_type | array | List of object types | No |
Parameter | file_extension | array | List of file extensions | No |
Parameter | title | string | Title filter | No |
Parameter | size | integer | Size filter | No |
Parameter | file_name | array | List of file names | No |
Parameter | repos | array | List of repositories | No |
Parameter | ext_user_id_ref | string | External user ID reference | No |
Parameter | system_metadata | object | System metadata including created_by, updated_by, is_deleted, license info, timestamps, etc. | No |
Parameter | custom_metadata | object | Custom metadata (tags, kvp, taxonomy) | No |
Parameter | media_metadata | object | Media-specific metadata | No |
Parameter | source_system_metadata | object | Source system metadata (source_system_id, connector_info, source_url) | No |
3. Basic Search
POST /cl/search/api/v2/basic_search
Description: Basic search functionality with advanced filtering options.
Request Payload:
Type | Parameter | Type | Description | Required |
---|---|---|---|---|
Query Parameter | query_string | string | Query string to search for objects | Yes |
Query Parameter | sorting_by | string | Sorting by (Available values: None, Default: None) | No |
Query Parameter | order | string | Sort result in ascending or descending order (Default: asc) | No |
Query Parameter | page_no | integer | Page number (Minimum: 1, Default: 1) | No |
Query Parameter | page_size | integer | Page size (Default: 20) | No |
Parameter | object_ids | array | List of object IDs | No |
Parameter | folders | array | List of folders | No |
Parameter | object_type | array | List of object types | No |
Parameter | file_extension | array | List of file extensions | No |
Parameter | title | string | Title filter | No |
Parameter | size | integer | Size filter | No |
Parameter | file_name | array | List of file names | No |
Parameter | repos | array | List of repositories | No |
Parameter | ext_user_id_ref | string | External user ID reference | No |
Parameter | system_metadata | object | System metadata including created_by, updated_by, etc. | No |
Parameter | custom_metadata | object | Custom metadata (tags, kvp, taxonomy) | No |
Parameter | media_metadata | object | Media-specific metadata | No |
Parameter | source_system_metadata | object | Source system metadata (source_system_id, connector_info, source_url) | No |
Parameter | with_exact_search | boolean | Perform exact match search | No |
Parameter | with_highlight | boolean | Highlight matching terms | No |
Parameter | is_anywhere | boolean | Perform anywhere search | No |
4. Re-ranked Search
POST /cl/search/api/v2/search
Description: Re-ranks search results from semantic and full-text search.
Request Payload:
Type | Parameter | Description | Required |
---|---|---|---|
Query Parameter | query_string | Search query | Yes |
Query Parameter | re_ranked | Enable re-ranking (Default value: true) | Yes |
Query Parameter | page_no | Page number (Default value: 1, minimum: 1) | No |
Query Parameter | page_size | Page size (Default value: 20, minimum: 20) | No |
Parameter | object_ids | List of object IDs | Yes |
Parameter | folders | List of folders | Yes |
Parameter | object_type | List of object types | Yes |
Parameter | file_extension | List of file extensions | Yes |
Parameter | title | Title of the object | Yes |
Parameter | size | Size of the object | Yes |
Parameter | file_name | List of file names | Yes |
Parameter | repos | List of repositories | Yes |
Parameter | ext_user_id_ref | External user ID reference | Yes |
Parameter | system_metadata | Metadata for system (created_by, updated_by, etc.) | Yes |
Parameter | custom_metadata | Custom metadata (tags, kvp, taxonomy) | Yes |
Parameter | media_metadata | Metadata related to media | Yes |
Parameter | source_system_metadata | Source system metadata (source_system_id, source_url, etc.) | Yes |
Common Response Format
{
"status": "200",
"message": "Documents found",
"result_count": 0,
"result": [],
"aggregation": {}
}
5. Re-ranked Chunk Search
POST /cl/search/api/v2/chunk/search
Description: Enables re-ranking of search results based on semantic and full-text search relevance.
Request Payload:
Type | Parameter | Description | Required |
---|---|---|---|
Query Parameter | query_string | Query string for semantic search | Yes |
Query Parameter | page_size | Items per page (Default value: 5) | No |
Query Parameter | page_no | Page number (Default value: 1) | No |
Parameter | object_ids | List of object IDs | Yes |
Parameter | custom_metadata | Custom metadata (tags, kvp, taxonomy) | Yes |
Common Response Format
{
"status": "200",
"message": "Request successful",
"result_count": 0,
"result": [],
"aggregation": {},
"error": null
}
Response Status Codes
Code | Description |
---|---|
200 | Documents found |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Object not found |
405 | Method not allowed |
422 | Unprocessable Entity |
500 | Internal server error |
Search Features
Basic Features
- Exact match searching
- Highlight support
- Anywhere search
- Combined objects search
- Folder-only search
Advanced Features
- Semantic search capabilities
- Full-text search with relevance scoring
- Re-ranking of search results
- Query classification
- Chunk-based search
Pagination
All search endpoints support pagination with:
- page_no: Page number (starts from 1)
- page_size: Number of results per page
Common Request Parameters
Search Filters
- object_ids: Filter by specific object IDs
- folders: Filter by folders
- object_type: Filter by content types (Document, Audio, Video, etc.)
- file_extension: Filter by file types (pdf, docx, mp4, etc.)
- title: Filter by title
- size: Filter by size
- file_name: Filter by file names
- repos: Filter by repositories
Metadata Filters
-
System Metadata
- created_by
- updated_by
- is_private
- is_deleted
- license information
- timestamps
-
Custom Metadata
- tags
- key-value pairs (kvp)
- taxonomy
-
Media Metadata
- Custom media-specific properties
-
Source System Metadata
- source_system_id
- connector_info
- source_url